Prevents bad commit or push (git hooks, pre-commit/precommit, pre-push/prepush, post-merge/postmerge and all that stuff...)
Husky is an npm package that allows you to manage Git hooks easily. It lets you run scripts at specific points in your Git workflow, such as before committing or pushing code. This helps in automating tasks like code linting, testing, and validation before these actions take place, ensuring code quality and consistency.
Pre-commit Hook
This feature allows you to run commands before a commit is made. In this example, `npm test` and `npm run lint` are executed before each commit, ensuring that tests pass and the code is linted.
"husky": {
"hooks": {
"pre-commit": "npm test && npm run lint"
}
}Pre-push Hook
This feature allows you to run commands before code is pushed to the repository. In this example, `npm run build` is executed before each push, ensuring that the build is updated.
"husky": {
"hooks": {
"pre-push": "npm run build"
}
}Commit-msg Hook
This feature allows you to run a script to validate the commit message. In this example, `validate-commit-msg.js` is a script that checks if the commit message follows a certain format.
"husky": {
"hooks": {
"commit-msg": "./validate-commit-msg.js"
}
}Lint-staged is similar to Husky in that it is often used in conjunction with Husky to run linters on staged files in Git. It does not manage Git hooks itself but is designed to run scripts on files that are staged for commit.
Pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. It is similar to Husky but is language-agnostic and can be used outside of the Node.js ecosystem. It requires a separate installation and configuration.
Git hooks made easy
Husky can prevent bad git commit, git push and more š¶ woof!
Announcement: Husky v5 has been published, to view v5 docs click here.
Note to npm v7 users: if hooks aren't being installed with npm v7, check that your version is at least v7.1.2.
This will install husky v4.
npm install husky --save-dev
// package.json
{
"husky": {
"hooks": {
"pre-commit": "npm test",
"pre-push": "npm test",
"...": "..."
}
}
}
git commit -m 'Keep calm and commit'
Existing hooks are kept. Requires Node >= 10 and Git >= 2.13.0.
If Husky is already in your node_modules or pnp.js (Yarn 2) and you want to reinstall hooks, you can run npm rebuild or yarn rebuild.
npm uninstall husky
Git hooks installed by husky will be removed.
Does your company use Husky? Ask your manager or marketing team if your company would be interested in supporting this project.
Find Husky helpful? Become a backer and show your appreciation with a monthly donation on Open Collective. You can also tip with a one-time donation.
GitHub sponsors can be viewed on my profile. All past and current Open Collective sponsors can be viewed on Husky's Open Collective.
Run husky-upgrade to automatically upgrade your configuration:
npx --no-install husky-upgrade
You can also do it manually. Move your existing hooks to husky.hooks field and use raw Git hooks names. Also, if you were using GIT_PARAMS env variable, rename it to HUSKY_GIT_PARAMS.
{
"scripts": {
- "precommit": "npm test",
- "commitmsg": "commitlint -E GIT_PARAMS"
},
+ "husky": {
+ "hooks": {
+ "pre-commit": "npm test",
+ "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+ }
+ }
}
Starting with 1.0.0, husky can be configured using .huskyrc, .huskyrc.json, .huskyrc.yaml, .huskyrc.yml, .huskyrc.js or husky.config.js file.
// .huskyrc
{
"hooks": {
"pre-commit": "npm test"
}
}
Husky supports all Git hooks defined here. Server-side hooks (pre-receive, update and post-receive) aren't supported.
Git hooks can get parameters via command-line arguments and stdin. Husky makes them accessible via HUSKY_GIT_PARAMS and HUSKY_GIT_STDIN environment variables.
"commit-msg": "echo $HUSKY_GIT_PARAMS"
During a rebase you may want to skip all hooks, you can use HUSKY_SKIP_HOOKS environment variable.
HUSKY_SKIP_HOOKS=1 git rebase ...
If you don't want husky to automatically install Git hooks, simply set HUSKY_SKIP_INSTALL environment variable.
HUSKY_SKIP_INSTALL=1 npm install
By default, Husky won't install on CI servers.
If you have a multi-package repository, it's recommended to use tools like lerna and have husky installed ONLY in the root package.json to act as the source of truth.
Generally speaking, you should AVOID defining husky in multiple package.json, as each package would overwrite previous husky installation.
.
āāā root
āāā .git
āāā package.json š¶ # Add husky here
āāā packages
āāā A
ā āāā package.json
āāā B
ā āāā package.json
āāā C
āāā package.json
// root/package.json
{
"private": true,
"devDependencies": {
"husky": "..."
},
"husky": {
"hooks": {
"pre-commit": "lerna run test"
}
}
}
If you're on Windows, husky will simply use the version installed globally on your system.
For macOS and Linux users:
git commands in the terminal, husky will use the version defined in your shell PATH. In other words, if you're a nvm user, husky will use the version that you've set with nvm.nvm, it may have a different PATH and not load nvm, in this case the highest node version installed by nvm will usually be picked. You can also check ~/.node_path to see which version is used by GUIs and edit if you want to use something else.Husky will source ~/.huskyrc file if it exists before running hook scripts.
You can use it, for example, to load a node version manager or run some shell commands before hooks.
# ~/.huskyrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
By design and just like scripts defined in package.json, husky will run hook scripts as a single command.
"pre-commit": "cmd && cmd"
That said, if you prefer to use an array, the recommended approach is to define them in .huskyrc.js or husky.config.js.
const tasks = (arr) => arr.join(' && ')
module.exports = {
hooks: {
'pre-commit': tasks(['cmd', 'cmd']),
},
}
Tools like npm-run-all can help too.
HUSKY_DEBUG=1 can provide additional information when running commands.
HUSKY_DEBUG=1 npm install husky --save-dev
HUSKY_DEBUG=1 git commit ...
Check if hooks were installed. Verify that .git/hooks/pre-commit exists and have husky code. It should start with:
#!/bin/sh
# husky...
If not, you may have another Git hooks manager defined in your package.json overwriting husky's hooks. Check also the output during install, you should see:
husky > Setting up git hooks
husky > Done
For a commit to be blocked, pre-commit script must exit with a non-zero exit code. If you commit isn't blocked, check your script exit code.
Husky is fast and only adds a few tenth of seconds to commits (~0.3s on a low-end PC). So it's most probably related to how many things are done during pre-commit. You can often improve this by using cache on your tools (babel, eslint, ...) and using lint-staged.
To isolate your issue, you can also create a new repo:
mkdir foo && cd foo
git init && npm init -y
npm install husky --save-dev
# Add a failing pre-commit hook to your package.json:
# "pre-commit": "echo \"this should fail\" && exit 1"
# Make a commit
Verify that your version of Git is >=2.13.0.
People and companies supporting via Patreon: thanks
MIT
FAQs
Modern native Git hooks
The npm package husky receives a total of 2,438,798 weekly downloads. As such, husky popularity was classified as popular.
We found that husky demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.